/*
 * IMatrixReader.cs
 *
 * Interface for creating a matrix from a file or stream
 *
 * Copyright (c) 2005, dnAnalytics. All rights reserved.
 */
using System;
using System.IO;
using dnAnalytics.LinearAlgebra;

namespace dnAnalytics.LinearAlgebra.IO
{
    /// <summary>
    /// Interface to read a matrix from a file or stream.
    /// </summary>
    public interface IMatrixReader
    {
        /// <summary>
        /// Reads a <see cref="Matrix"/> from a file.
        /// </summary>
        /// <param name="file">The file to read the matrix from.</param>
        /// <returns>A <see cref="Matrix"/> containing the data from the file. <b>null</b> is returned if the file is empty.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="file"/> is <b>null</b>.</exception>
        /// <exception cref="IOException">If the file doesn't exist.</exception>
        /// <exception cref="FormatException">If a value is not a number or not in a valid format.</exception>
        /// <exception cref="OverflowException">If a value represents a number less than <see cref="Double.MinValue"/> or greater than <see cref="Double.MaxValue"/>.</exception>
        Matrix ReadMatrix(string file);

        /// <summary>
        /// Reads a <see cref="Matrix"/> from a <see cref="Stream"/>.
        /// </summary>
        /// <param name="stream">The <see cref="Stream"/> to read the matrix from.</param>
        /// <returns>A matrix containing the data from the <see cref="Stream"/>. <b>null</b> is returned if the <see cref="Stream"/> is empty.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="stream"/> is <b>null</b>.</exception>
        /// <exception cref="FormatException">If a value is not a number or not in a valid format.</exception>
        /// <exception cref="OverflowException">If a value represents a number less than <see cref="Double.MinValue"/> or greater than <see cref="Double.MaxValue"/>.</exception>
        Matrix ReadMatrix(Stream stream);

        /// <summary>
        /// Reads a <see cref="Matrix"/> from a <see cref="TextReader"/>.
        /// </summary>
        /// <param name="reader">The <see cref="TextReader"/> to read the matrix from.</param>
        /// <returns>A matrix containing the data from the <see cref="TextReader"/>. <b>null</b> is returned if the <see cref="TextReader"/> is empty.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="reader"/> is <b>null</b>.</exception>
        /// <exception cref="FormatException">If a value is not a number or not in a valid format.</exception>
        /// <exception cref="OverflowException">If a value represents a number less than <see cref="Double.MinValue"/> or greater than <see cref="Double.MaxValue"/>.</exception>
        Matrix ReadMatrix(TextReader reader);

        /// <summary>
        /// Reads an <see cref="Matrix"/> from a file.
        /// </summary>
        /// <param name="file">The file to read the matrix from.</param>
        /// <param name="matrixType">The type of matrix to return.</param>
        /// <returns>A matrix containing the data from the file. <b>null</b> is returned if the file is empty.</returns>
        /// <exception cref="IOException">If the file doesn't exist.</exception>
        /// <exception cref="FormatException">If a value is not a number or not in a valid format.</exception>
        /// <exception cref="OverflowException">If a value represents a number less than <see cref="Double.MinValue"/> or greater than <see cref="Double.MaxValue"/>.</exception>
        Matrix ReadMatrix(string file, MatrixType matrixType);

        /// <summary>
        /// Reads an <see cref="Matrix"/> from a <see cref="Stream"/>.
        /// </summary>
        /// <param name="stream">The <see cref="Stream"/> to read the matrix from.</param>
        /// <param name="matrixType">The type of matrix to return.</param>
        /// <returns>A matrix containing the data from the <see cref="Stream"/>. <b>null</b> is returned if the <see cref="Stream"/> is empty.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="stream"/> is <b>null</b>.</exception>
        /// <exception cref="FormatException">If a value is not a number or not in a valid format.</exception>
        /// <exception cref="OverflowException">If a value represents a number less than <see cref="Double.MinValue"/> or greater than <see cref="Double.MaxValue"/>.</exception>
        Matrix ReadMatrix(Stream stream, MatrixType matrixType);

        /// <summary>
        /// Reads an <see cref="Matrix"/> from a <see cref="TextReader"/>.
        /// </summary>
        /// <param name="reader">The <see cref="TextReader"/> to read the matrix from.</param>
        /// <param name="matrixType">The type of matrix to return.</param>
        /// <returns>A matrix containing the data from the <see cref="TextReader"/>. <b>null</b> is returned if the <see cref="TextReader"/> is empty.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="reader"/> is <b>null</b>.</exception>
        /// <exception cref="FormatException">If a value is not a number or not in a valid format.</exception>
        /// <exception cref="OverflowException">If a value represents a number less than <see cref="Double.MinValue"/> or greater than <see cref="Double.MaxValue"/>.</exception>
        Matrix ReadMatrix(TextReader reader, MatrixType matrixType);
    }
}